<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Cluster reroute API | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'cluster-reroute.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/cluster-reroute.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/cluster-reroute.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/cluster-reroute.html" rel="nofollow" target="_blank">../en/cluster-reroute.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="cluster.html">Cluster APIs</a></span>
»
<span class="breadcrumb-node">Cluster reroute API</span>
</div>
<div class="navheader">
<span class="prev">
<a href="cluster-health.html">« Cluster health API</a>
</span>
<span class="next">
<a href="cluster-state.html">Cluster state API »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="cluster-reroute"></a>Cluster reroute API<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/reroute.asciidoc">edit</a>
</h2>
</div></div></div>

<p>Changes the allocation of shards in a cluster.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-reroute-api-request"></a>Request<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/reroute.asciidoc">edit</a>
</h3>
</div></div></div>
<p><code class="literal">POST /_cluster/reroute</code></p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-reroute-api-desc"></a>Description<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/reroute.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The reroute command allows for manual changes to the allocation of individual
shards in the cluster. For example, a shard can be moved from one node to
another explicitly, an allocation can be cancelled, and an unassigned shard can
be explicitly allocated to a specific node.</p>
<p>It is important to note that after processing any reroute commands Elasticsearch will
perform rebalancing as normal (respecting the values of settings such as
<code class="literal">cluster.routing.rebalance.enable</code>) in order to remain in a balanced state. For
example, if the requested allocation includes moving a shard from <code class="literal">node1</code> to
<code class="literal">node2</code> then this may cause a shard to be moved from <code class="literal">node2</code> back to <code class="literal">node1</code> to
even things out.</p>
<p>The cluster can be set to disable allocations using the
<code class="literal">cluster.routing.allocation.enable</code> setting. If allocations are disabled then
the only allocations that will be performed are explicit ones given using the
<code class="literal">reroute</code> command, and consequent allocations due to rebalancing.</p>
<p>It is possible to run <code class="literal">reroute</code> commands in "dry run" mode by using the
<code class="literal">?dry_run</code> URI query parameter, or by passing <code class="literal">"dry_run": true</code> in the request
body. This will calculate the result of applying the commands to the current
cluster state, and return the resulting cluster state after the commands (and
re-balancing) has been applied, but will not actually perform the requested
changes.</p>
<p>If the <code class="literal">?explain</code> URI query parameter is included then a detailed explanation
of why the commands could or could not be executed is included in the response.</p>
<p>The cluster will attempt to allocate a shard a maximum of
<code class="literal">index.allocation.max_retries</code> times in a row (defaults to <code class="literal">5</code>), before giving
up and leaving the shard unallocated. This scenario can be caused by
structural problems such as having an analyzer which refers to a stopwords
file which doesn’t exist on all nodes.</p>
<p>Once the problem has been corrected, allocation can be manually retried by
calling the <code class="literal">reroute</code> API with the <code class="literal">?retry_failed</code> URI
query parameter, which will attempt a single retry round for these shards.</p>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-reroute-api-query-params"></a>Query parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/reroute.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">dry_run</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, then the request simulates the operation only
and returns the resulting state.
</dd>
<dt>
<span class="term">
<code class="literal">explain</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, then the response contains an explanation of
why the commands can or cannot be executed.
</dd>
<dt>
<span class="term">
<code class="literal">metric</code>
</span>
</dt>
<dd>
<p>
(Optional, string) Limits the information returned to the specified metrics.
Defaults to all but metadata The following options are available:
</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">_all</code>
</span>
</dt>
<dd>
Shows all metrics.
</dd>
<dt>
<span class="term">
<code class="literal">blocks</code>
</span>
</dt>
<dd>
Shows the <code class="literal">blocks</code> part of the response.
</dd>
<dt>
<span class="term">
<code class="literal">master_node</code>
</span>
</dt>
<dd>
Shows the elected <code class="literal">master_node</code> part of the response.
</dd>
<dt>
<span class="term">
<code class="literal">metadata</code>
</span>
</dt>
<dd>
Shows the <code class="literal">metadata</code> part of the response. If you supply a comma separated
list of indices, the returned output will only contain metadata for these
indices.
</dd>
<dt>
<span class="term">
<code class="literal">nodes</code>
</span>
</dt>
<dd>
Shows the <code class="literal">nodes</code> part of the response.
</dd>
<dt>
<span class="term">
<code class="literal">routing_table</code>
</span>
</dt>
<dd>
Shows the <code class="literal">routing_table</code> part of the response.
</dd>
<dt>
<span class="term">
<code class="literal">version</code>
</span>
</dt>
<dd>
Shows the cluster state version.
</dd>
</dl>
</div>
</dd>
<dt>
<span class="term">
<code class="literal">retry_failed</code>
</span>
</dt>
<dd>
(Optional, boolean) If <code class="literal">true</code>, then retries allocation of shards that are
blocked due to too many subsequent allocation failures.
</dd>
<dt>
<span class="term">
<code class="literal">master_timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a connection to the master node. If no response is received before the timeout
expires, the request fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
<dt>
<span class="term">
<code class="literal">timeout</code>
</span>
</dt>
<dd>
(Optional, <a class="xref" href="common-options.html#time-units" title="Time units">time units</a>) Specifies the period of time to wait for
a response. If no response is received before the timeout expires, the request
fails and returns an error. Defaults to <code class="literal">30s</code>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-reroute-api-request-body"></a>Request body<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/reroute.asciidoc">edit</a>
</h3>
</div></div></div>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">commands</code>
</span>
</dt>
<dd>
<p>
(Required, object) Defines the commands to perform. Supported commands are:
</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">move</code>
</span>
</dt>
<dd>
Move a started shard from one node to another node. Accepts <code class="literal">index</code> and
<code class="literal">shard</code> for index name and shard number, <code class="literal">from_node</code> for the node to move
the shard from, and <code class="literal">to_node</code> for the node to move the shard to.
</dd>
<dt>
<span class="term">
<code class="literal">cancel</code>
</span>
</dt>
<dd>
Cancel allocation of a shard (or recovery). Accepts <code class="literal">index</code> and <code class="literal">shard</code> for
index name and shard number, and <code class="literal">node</code> for the node to cancel the shard
allocation on. This can be used to force resynchronization of existing
replicas from the primary shard by cancelling them and allowing them to be
reinitialized through the standard recovery process. By default only
replica shard allocations can be cancelled. If it is necessary to cancel
the allocation of a primary shard then the <code class="literal">allow_primary</code> flag must also
be included in the request.
</dd>
<dt>
<span class="term">
<code class="literal">allocate_replica</code>
</span>
</dt>
<dd>
Allocate an unassigned replica shard to a node. Accepts <code class="literal">index</code> and <code class="literal">shard</code>
for index name and shard number, and <code class="literal">node</code> to allocate the shard to. Takes
<a class="xref" href="modules-cluster.html" title="Cluster-level shard allocation and routing settings">allocation deciders</a> into account.
</dd>
</dl>
</div>
</dd>
</dl>
</div>
<p>Two more commands are available that allow the allocation of a primary shard to
a node. These commands should however be used with extreme care, as primary
shard allocation is usually fully automatically handled by Elasticsearch. Reasons why a
primary shard cannot be automatically allocated include the
following:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
A new index was created but there is no node which satisfies the allocation
deciders.
</li>
<li class="listitem">
An up-to-date shard copy of the data cannot be found on the current data
  nodes in the cluster. To prevent data loss, the system does not automatically
promote a stale shard copy to primary.
</li>
</ul>
</div>
<p>The following two commands are dangerous and may result in data loss. They are
meant to be used in cases where the original data can not be recovered and the
cluster administrator accepts the loss. If you have suffered a temporary issue
that can be fixed, please see the <code class="literal">retry_failed</code> flag described above. To
emphasise: if these commands are performed and then a node joins the cluster
that holds a copy of the affected shard then the copy on the newly-joined node
will be deleted or overwritten.</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">allocate_stale_primary</code>
</span>
</dt>
<dd>
Allocate a primary shard to a node that holds a stale copy. Accepts the
<code class="literal">index</code> and <code class="literal">shard</code> for index name and shard number, and <code class="literal">node</code> to allocate
the shard to. Using this command may lead to data loss for the provided
shard id. If a node which has the good copy of the data rejoins the cluster
later on, that data will be deleted or overwritten with the data of the
stale copy that was forcefully allocated with this command. To ensure that
these implications are well-understood, this command requires the flag
<code class="literal">accept_data_loss</code> to be explicitly set to <code class="literal">true</code>.
</dd>
<dt>
<span class="term">
<code class="literal">allocate_empty_primary</code>
</span>
</dt>
<dd>
Allocate an empty primary shard to a node. Accepts the <code class="literal">index</code> and <code class="literal">shard</code>
for index name and shard number, and <code class="literal">node</code> to allocate the shard to. Using
this command leads to a complete loss of all data that was indexed into
this shard, if it was previously started. If a node which has a copy of the
data rejoins the cluster later on, that data will be deleted. To ensure
that these implications are well-understood, this command requires the flag
<code class="literal">accept_data_loss</code> to be explicitly set to <code class="literal">true</code>.
</dd>
</dl>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="cluster-reroute-api-example"></a>Examples<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/cluster/reroute.asciidoc">edit</a>
</h3>
</div></div></div>
<p>This is a short example of a simple reroute API call:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /_cluster/reroute
{
    "commands" : [
        {
            "move" : {
                "index" : "test", "shard" : 0,
                "from_node" : "node1", "to_node" : "node2"
            }
        },
        {
          "allocate_replica" : {
                "index" : "test", "shard" : 1,
                "node" : "node3"
          }
        }
    ]
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1392.console"></div>
</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="cluster-health.html">« Cluster health API</a>
</span>
<span class="next">
<a href="cluster-state.html">Cluster state API »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>